# Rewrite the &MacPerl'function()s if you want to run SgmlForm on another machine.
# SgmlForm runs without any argument.
#
#------------------------------ About SgmlForm -----------------------------------
#
# SgmlForm is FREE software.
# I grant to any user an royalty-free, worldwide, non-exclusive license to use, execute, reproduce, display, perform and distribute copies of SgmlForm.
# SgmlForm processes the ESIS-formatted data that is generated by SGML-parser `MacSgmls'.
# SgmlForm reads the source-file(ESIS-formatted), and generates the target-file(text-file for TeX or PageMaker) while referring to the map-info-file.
# SgmlForm is operated by special commands.
# SgmlsForm was developed by KISI,KAZUTAKA.
# Write me when you detected any error.
# Also write me when you adapted to new version.
# The English writing is my weak point.
# If you will correct this document, I am very glad.
(1) SgmlForm is FREE software. I grant to any user an royalty-free, worldwide, non-exclusive license to use, execute, reproduce, display, perform and distribute copies of SgmlForm. I do not warrant the result that issued from running SgmlForm.
(2) SgmlForm inputs the source-file(ESIS-formatted) that is generated by SGML-parser `MacSgmls', and outputs the target-file(text-file for TeX or PageMaker) while referring to the map-info.
(3) SgmlForm is launched with no argument and operated by special commands.
(4) SgmlsForm was developed by KISI,KAZUTAKA. Write me when you detected any error. Also write me when you adapted to new version.
e-mail : NAG00251@niftyserve.or.jp
2 Bug Report of SgmlForm
2.1 ver.1.0 to 1.2
before open
2.2 ver.1.3 (96.8.28)
first open to public
2.3 ver.1.4 (96.9.20)
I am sorry that the map-info in this version is not compatible with it in previous version.
(1) The messages were corrected.
(2) The map-info-file distinguishes by the DTD that is included in the source-file.
(3) The TEXT as the file extension was added.
(4) The arguments format of build-in function &Value() was altered.
(5) The reference format in replacing-string was altered.
(6) Several build-in functions were added.
(7) Several commands were added.
(8) The environment variable was added.
(9) The help message and online manual can be changed to either Japanese or English.
(10) A line is divided into each part by CR. It may be possible to escape an expected crash for the memory saving.
3 Files in SgmlForm
(1) SgmlForm distinguishes each related files by the following file extension.
(3.1) Let us suppose the document instance is `ReadMe' that is based on the document-type-definition `TEXTBOOK.DTD'. MacSgmls will read both files, and will output the file `ReadMe.esi'.
(3.2) Make up the map-info-file `TEXTBOOK.MPM' if you map the `ReadMe.esi' onto the PageMaker. MacSgmls will read the `ReadMe.esi' while referring to the `TEXTBOOK.MPM', and will output the target-file `ReadMe.pm'. Finally, the PageMaker will read the `ReadMe.pm'.
(3.3) Make up the map-info-file `TEXTBOOK.MTX' if you map the `ReadMe.esi' onto the TeX. MacSgmls will read the `ReadMe.esi' while referring to the `TEXTBOOK.MTX', and will output the target-file `ReadMe.tex'. Finally, the TeX will read the `ReadMe.tex'.
4 Commands of SgmlForm
(1) The format of command line :
f{d}[s][m][t(c)] > command
Where,
----------------------------------------
Symbol Meaning
----------------------------------------
f the filename of source-file
d the filename of DTD-file
s the file extension of source-file
m the file extension of map-info-file
t the file extension of target-file
c the file creator of output-file
----------------------------------------
(2) Command :
----------------------------------------------
Symbol Command
----------------------------------------------
q quit
l set the number of lines displayed
c the number of columns displayed
? display the help message
d display the online manual
o save the online manual
v display the version of SgmlForm
r review the text file
t display the document type definition
s select the source-file(ESIS-format)
m select the mapping
a select the file creator of target-file
f form to the target from the source
i display the input text
x display the converted text
h Convert to HTML-format from the text-format
----------------------------------------------
5 Changing by SgmlForm
(1) SgmlForm reads the source file.
(1.1) The declared value is regarded as the ID value when the attribute name is `ID'. This attribute value is assigned an unique number.
(1.2) The declared value is regarded as the ID reference value when the attribute name is `REFID'. This attribute value is associated with an ID value.
(2) SgmlForm finds out the DTD that is described in the source-file, and finds out the map-info-file.
(3) SgmlForm refers to the map-info-file if the SGML-tag requests to replace.
(3.1) If the map-info includes the Perl-script SgmlForm performs it.
(3.2) If the map-info includes the replacing-string SgmlForm replaces it, and outputs the target-file.
(3.3) If the map-info includes no replacing-string SgmlForm do nothing.
(4) If the source is data SgmlForm outputs it.
(4.1) If data includes `\n' it is converted to a record-end-character.
(4.2) If data includes two `\' it is converted to one `\'.
(4.3) The output of a particular special characters that have to convert an escape characters can be defined using the built-in function &DefineEscape() and &Escape().
(4.4) The output of a particular characters that have to convert another characters can be defined using the built-in function &DefineReplace() and &Replace().
(4.5) The output can be suppressed using the build-in function &Inhibit().
(4.6) The output of record-end-character can be suppressed using the build-in function &DeleteCr().
6 Map-Info
(1) The map-info of SgmlForm is a series of lines. The an initial character of a line decides the format. Where, `->' means TAB-code.
SGML-tag->condition-expression
~->script
~-> •
~-> •
->replacing-string
-> •
-> •
-> •
SGML-tag->condition-expression
~->script
~-> •
~-> •
->replacing-string
-> •
-> •
-> •
(2) Lines can be arbitrarily long.
(3) The SGML-tag must be unique in map-info as a whole. The value of condition-expression must be unique in the combination if you specify two and more SGML-tags.
6.1 comment
(1) Format
!comment
(2) Function
(2.1) This line is a comment.
(2.2) You can write the comment in anywhere.
(3) Example
! This is a comment line.
6.2 SGML-tag and Condition-expression
(1) Format
(gid->condition-expression
)gid->condition-expression
C->condition-expression
(2) Function
(2.1) The left part of this line is a SGML-tag that requests the replacing.
(2.2) The right part of this line is a condition-expression. The condition-expression must be the Perl condition-expression. The replacing-process is caused if the return value of condition-expression is true. The replacing-process is always caused if the condition-expression is not specified.
(3) Example
(LI->$xlist
The replacing-process is caused when the value of variable `$xlist' is 1.
6.3 Replacing-String
(1) Format
->Replacing-String
(2) Function
(2.1) The right part of this line is a replacing-string for the SGML-tag.
(2.2) The replacing-string consists of one or more lines.
(2.3) The replacing-string is evaluated by the following rule, and is outputted.
(2.3.1) The `\n' in the replacing-string converts to a record-end-character.
(2.3.2) The `~aname~' in the replacing-string converts to the value corresponding to the attribute name `aname' in the current generic-identifier. The build-in function &Value() can refer to this value.
(2.3.3) The `~#gid_aname~' in the replacing-string converts to an unique number that is assigned to the value of attribute name `ID' and `REFID' in the generic-identifier `gid'. The build-in function &Refer() can refer to this value.
(2.3.4) The `~$vname~' in the replacing-string converts to the Perl value corresponding to the variable name `$vname'.
(3) Example
(3.1) Value of attribute `ID' and its Numbering
Assume the following ESIS-data was input and the value `HYPERCARD' of attribute `ID' of generic-identifier `FN' was assigned to 123.
AID TOKEN HYPERCARD
ATYPE TOKEN AUTHNOTE
(FN
-HyperCard is a trade mark of Apple Computer, Inc.
When `(FN' is input the following map-info acts.
(FN
->~ID~=~#FN_ID~
The following string is output.
HYPERCARD=123
(3.2) Refer to ID
Assume the following ESIS-data was input and the value `HYPERCARD' of attribute `ID' of generic-identifier `FN' was assigned to 123.
-DicSGML is the dictionary, is HyperCard
AREFID TOKEN HYPERCARD
APAGE TOKEN NO
(FNREF
)FNREF
-Stackware
When `(FNREF' is input the following map-info acts.
(FNREF
->~REFID~=~#FN_REFID~
The following string is output.
HYPERCARD=123
Notice that the example of replacing-string is not `~#FNREF_REFID~'. The generic-identifier that decided ID is `FN', not `FNREF'.
(3.3) Implied Value
Assume the following ESIS-data was input.
ANUMBER CDATA
AID IMPLIED
ASTITLE IMPLIED
(H1
(H1T
-MacSgmls
When `(H1' is input the following map-info acts.
(H1
->~ID~=~#H1_ID~
The following string is output. Both ~ID~ and ~#H1_ID~ are empty character.
=
6.4 Script
(1) Format
~->script
(2) Function
(2.1) The right part of this line is a Perl-script that should perform before the replacing-process.
(2.2) Do not use the control structure which consists of separated lines because SgmlForm performs a line to each phases.
(2.3) The initial of variable name in your script should be `$x'. Such variables can avoid the same word in SgmlForm variables.
(2.4) The following build-in functions are available.
7 Available Built-in Functions
7.1 Attribute Value, ID number
(1) Format
&Value(aname) get a value of attribute name `aname' of current generic-identifier
&Refer(gid, aname) get an unique number of identifier
(2) Function
(2.1) &Value() acts the same function as `~aname~'. &Refer() acts the same function as `~#gid_aname~'. Thus the attribute name of &Refer() must be either `ID' or `REFID'.
(2.2) The undefined value is returned when no value (IMPLIED) is given the attribute name.
(2.3) The attribute appears earlier than the start-tag in the source-file , but these build-in functions can use at both the start-tag and the end-tag.
(2.4) These build-in functions refer to the attribute of start-tag which corresponds to end-tag, when structure of SGML-tags consists of the nest.
(3) Example
(FIG
~->$xfigid = &Value('ID') ;
The value of ID-attribute of FIG-tag is assigned into a variable `$xfigid'. When the succeeding tag refers to `$xfigid' the ID becomes the number of the figure uniquely.
7.2 Hook Data
(1) Format
&Hook(gid) command that SgmlForm gets the data which corresponds to last generic-identifier `gid'
&Data(gid) get the data which is got by &Hook()
(2) Function
(2.1) The generic-identifier `gid' is the same to &Hook().
(2.2) Data is deleted if you refer to it once.
(3) Example
(TLINE
~->&Hook('TLINE') ;
•
•
(other
~->$xtline = &Data('TLINE') ;
In TLINE-start-tag, &Hook() commands that SgmlForm gets data which corresponds to last TLINE-tag. Its value is saved when SgmlForm reads TLINE-tag. In the other tag, &Data() assigns its value into the variable `$xtline'. Its value is deleted after assignment.
7.3 Inhibit Data Output
(1) Format
&Inhibit(gid)
(2) Function
(2.1) &Inhibit() commands the suppression of data which corresponds to next generic-identifier `gid'.
(2.2) &Inhibit() returns no value.
7.4 Convert Replacing-string
(1) Format
&Convert(chstr)
(2) Function
(2.1) &Convert() returns the replacing-string `chstr' which is evaluated.
7.5 Character Conversion
(1) Format
&DefineReplace(str1, str2) define a string `str1' as a string `str2'
&DefineEscape(schr, esc) define a special character `schr' as an escape string `esc'
&Replace(sw) replace if sw is 1, or else do nothing
&Escape(sw) escape if sw is 1, or else do nothing
&DeleteCr(sw) suppress CR(\n) if sw is 1, or else output
(2) Function
(2.1) These build-in functions command SgmlForm to replace the string in data by another string.
(2.2) The process during data output performs as follows ; the conversion of octal notation, the deletion of CR(`\n') denoted by &DeleteCr(), the replacing by &DefineEscape() and &Escape(), the replacing denoted by &DefineReplace() and &Replace().
(3) Example
~Å®&DeleteCr(1) ;
~Å®&DefineEscape('<','<') ;
~Å®&DefineEscape('>','>') ;
~Å®&DefineEscape('&','&') ;
~Å®&Escape(1) ;
7.6 Graphic Size
(1) Format
&GraphicSize(fname, ftype)
(2) Function
(2.1) &GraphicSize() returns the size (width and height) of picture which is expressed by filename `fname' and file type `ftype'. These values are an array variable.
The width of picture is assigned into `$xwidth'. The height of picture is assigned into `$xheight'. The file name is denoted by `~$xpath~~FILE~.~$xgraphic~'. When $xpath is 'MyDisk:GraphicData:', the value of FILE-attribute is 'DailogSample' and the variable `$xgraphic' is 'pict', the EPS file name is 'MyDisk:GraphicData:DailogSample.pict'.
7.7 Structure Control
(1) Format
&Begin(sname) command the beginning of the structure
&End(sname) command the end of the structure
&Level(sname) get a nested number in the structure
&Nest(sname) get a consecutive number in the structure
&Number(sname) get a consecutive number in the structure
&Count(sname) count the number of the structure
(2) Function
(2.1) These build-in functions control the structure. The structures are identified by the structure name.
(2.2) The structures are text such as the listing or chapter and section, are specified by start-tag and end-tag and may be the nest.
(2.3) The level of structures in nest is expressed by a consecutive number. Most shallow level is 1. More deeper level is increased in 1 each.
(2.4) The formats of structure number are as follows ;
(2.4.1) The structure number in the nest expression begins such as `1', `1.1', `1.1.1',... and increases such as `2', `1.2', `1.1.2',....
(2.4.2) The structure number in the terminal expression is most right number of the nest expression.
(3) Example
The following script performs the numbering and indentation in listing. The structure name `LI' acts to identify the listing. If the level of nest is 1 the number is such as `(1)', `(2)', `(3)', .... If the level of nest is two or more, the number is such as `(1.1)', `(1.2)', `(1.3)', ..., `(2.1)', `(2.2)', ... Each line indents another when the level is down.
(LI
~->&Begin('LI') ;
(IT
~->&Count('LI') ;
~->$xlleft = ' ' x &Level('LI') ;
~->$xlnest = &Nest('LI') ;
->\n~$xlleft~(~$xlnest~)
)LI
~->&End('LI') ;
~->$xlleft = ' ' x &Level('LI') ;
7.8 Display the String
(1) Format
&Display(str)
(2) Function
(2.1) &Display() display the string `str'. The dispaly is controlled by the lines and columns that are set by the command `l' and `c'.
(2.2) This build-in function uses for the debug mainly.
8 Convert to HTML-format from the text-format
(1) The text in left side of the following can convert to HTML in right side.
behaviour similar to virus <TR><TD>behaviour</TD><TD>similar to virus</TD></TR>
•
-------------------------------- </TABLE>
2.1 Origin of Bug <H2>Origin of Bug</H2>
Bugs were developed in 1940s... <P>Bugs were developed in 1940s...
•
•
2.2 Theory of Bug's Evolution <H2>Theory of Bug's Evolution</H2>
The following theory of evol... <P>The following theory of evol...
•
<OL>
(1) Development Period <LI>Development Period
(2) First Differentiation <LI>First Differentiation
<OL>
(2.1) Bug's Ancestor <LI>Bug's Ancestor
(2.2) Virus's Ancestor <LI>Virus's Ancestor
</OL>
(3) Differentiation by Selection <LI>Differentiation by Selection
•
</OL>
•
•
</BODY>
</HTML>
(2) The meaning of format is as follows ; Where, `d' means a number, `b' means a blank, `X•••' means that X may repeat, `[X]' means that X may be optional.
(2.1) File name and Title
# str
This description is converted to such as the following.
<TITLE>str</TITLE>
(2.2) Header
d[.d[.d]] b••• str
This description is converted to such as the following.
<Hn>str</Hn>
Where, `n' is the number of `d'(i.e. deep of level).
(2.3) Paragraph
b str
This description is converted to such as the following.
<P>str
(2.4) Preformatted string
bb••• str
This description is converted to such as the following.
<PRE>
<LI>str
•
•
</PRE>
(2.5) Numbered List
(d[.d[.d]]) b••• str
This description is converted to such as the following. The nest is structured on depending upon the number of `d'(i.e. deep of level).
<OL>
<LI>str
•
<OL>
<LI>str
•
</OL>
<LI>str
•
</OL>
(2.6) Table
(2.6.1) The table is divided in one header and details by hyphens.
---------------------------
bb••• Header
---------------------------
bb••• Detail
•
•
---------------------------
This description is converted to such as the following.
<TABLE BORDER=1>
Converted Header
Converted Detail
•
•
</TABLE>
(2.6.2) Header
bb••• str1 [bb••• str2 ]•••
The description of Header is converted to such as the following.
<TR><TH>str1</TH><TH>str2</TH>•••</TR>
(2.6.2) Detail
The description of Detail is converted to such as the following.
<TR><TD>str1</TD><TD>str2</TD>•••</TR>
(2.7) Graphic data name and Alternation name
* b•• str1 [ b•• str2 ]
This description is converted to such as the following.